Compiling and Testing Your Code
===============================

Each student's repository contains a global ``dune-project`` file and
one ``dune`` file in every directory that contains source code. These
are configuration files to ease compiling your code and unit-testing
it.  It is based on the `Dune <https://dune.build/>`_ tool helping you
to *build executables, libraries, run tests, and much more* with
``OCaml``.  We'll be describing the main command-lines you can use
within a unix system where ``OCaml`` and ``Dune`` have been properly
installed. For steps to make a Windows or a linux distribution
configuration of needed dependencies through ``opam`` please visit the
:doc:`FAQ`.

You'll have enough insight going through the quickstart page of the ``Dune``
documentation you can find `here
<https://dune.readthedocs.io/en/stable/overview.html>`_. For any in-depth use of
``Dune`` you're advised to have a look at the rest of the `offical documentation
<https://dune.readthedocs.io/en/stable/index.html>`_.

For testing purposes you might want to have a look at the ``Alcotest``
documentation : `Alcotest <https://github.com/mirage/alcotest/>`_.

.. DANGER::

   If you do not understand what you're doing **DO NOT** modify your
   ``dune-project`` or ``dune`` files without backing it up. Such a
   change might compromise your project compilation process. Know that
   your code will be graded using our own versions of these files, if
   you count on a modified build configuration to work out with
   grading process : you are mistaken.

.. contents:: Table of Contents
   :depth: 2
   :local:

Compiling Your Project
----------------------

You're having a ``dune-project`` file at the root of your
repository. This is the entry point for the configuration files meant
to set the scope of your project.  Every other ``dune`` file contains
information about what source files should be compiled, how, and with
what dependencies.

Contrary to a lot of (more elaborate) projects, there is no need for a
configuration step, you can directly compile your project using the command::

  dune build

from within the root of your project repository. This will create a ``_build/``
directory containing a copy of your source files and their respective
compilation products.

.. DANGER::
   We advise you to never modify the source files within that ``_build/``
   directory, these files will be overwritten by the "real" ones (those in
   ``Source/``) every time you do a build or clean command.

If at any time you need to get rid of this ``_build/`` folder and the
compilation products (to do a fresh and complete new build for example), you can
issue the following command::

  dune clean

Testing Your Project
--------------------

From The Shell
^^^^^^^^^^^^^^

Each repository comes with a number of unit tests included within the
``tests`` folders of each one of the project's phases. These are
written using the ``Alcotest`` testing library provided for
``OCaml``. You are welcome to add your own tests there if you
understand what you are doing, but a lot of them are already given to
you.

You can the whole test suite you're given by simply typing the command::

  dune runtest

This shall run three test suites: one for the `Builtin` part of the
project, one for the `Scalable` part and one for the `Zarithing` part
(for which tests are empty!). You will see three lists of tests: one
for each one of those parts. In these lists, each line corresponds to
one function and has four columns:

- the first column is the function's tests result (``[OK]`` if all the tests
  passed, ``[ERROR]`` if at least one did not, and something else in other, more
  specific, cases)
- the second column is the name of the module in which the function is
- the third column is the number of the function within that module
- the fourth and last column is a short description of the tested function

Below this list, if some tests failed, you will see a description of
the first few failed tests and the path of the file that contains the
detailed results of this module's tests.

If you only wish to run the tests of one of the three parts of that
project, you can restrict the tests ran by Dune by giving it the
folder you wish to test. For example, to only run the tests of the
`Builtin` part of the project, you can issue::

  dune runtest Source/builtin

If you want to further restrict what's ran and you only want to run
the tests of a single source file, you can directly run the test
executable and give it the name of the module you wish to test (each
source file is a module).

There are two ways of doing that: either you execute that file
directly after finding it in the ``_build`` directory. For example if
you only wish to run the `basic_arithmetics.ml` tests from the
`Builtin` part of the project you can type (don't forget the starting
dot)::

  ./_build/default/Source/tests/builtin/run_tests.exe test basic_arithmetics

or you can ask dune to find and run it itself by giving it the executable's expected
location relative to the source directory::

  dune exec Source/tests/builtin/run_tests.exe test basic_arithmetics

In this case you'll see that the whole test list is still displayed, but every
test you didn't specify is marked as ``[SKIP]``.


From within Emacs
^^^^^^^^^^^^^^^^^

You can test your functions from within the `OCaml top-level` available while
being in ``emacs`` ``tuareg-mode`` .

While being in the ``builtin`` directory you can evaluate each one of
the expressions of the ``builtin.ml`` file in the ``ocaml top-level``
interpreter by using the ``C-c C-e`` shortcut. In order to evaluate
the whole current buffer you can use the ``C-c C-b`` shortcut. To
evaluate the ``builtin.ml`` file without necessarily opening it you
can use the ``top-level`` directive::

  #use "builtin.ml"

All available function within the ``builtin.ml`` file are then
available within ``top-level``.

The previous strategy is going to raise an error if you try evaluating
the file ``basic_arithmetics.ml``. You'll get an error specifying that
the ``Builtin`` module is not bounded. This error says the
``top-level`` environment cannot see any ``Builtin`` module to open ;
the ``basic_arithmetics.ml`` file starts by openning that module
(which corresponds to file ``builtin.ml``). For ``top-level`` to
evaluate the ``open Builtin`` instruction you need to load
``builtin.ml`` as a module in ``top-level`` using the directive::

  #mod_use "builtin.ml"

You can then evaluate ``basic_arithmetics.ml`` using the directive::

  #use "basic_arithmetics.ml"

In order to evaluate any given file ``file.ml`` in ``top-level``
you'll generally need to load the modules it opens through ``open``
instructions using ``#mod_use`` directive. You're invited to ask your
lab assistants for help if needed.